Puppeteer

Puppeteer는 Puppeteer를 사용하여 브라우저 자동화 기능을 제공하는 Model Context Protocol 서버입니다. 이 서버는 LLM이 웹 페이지와 상호 작용하고, 스크린샷을 찍고, 실제 브라우저 환경에서 JavaScript를 실행할 수 있게 해줍니다.

특징

• 브라우저 자동화: 웹 사이트 탐색 및 상호 작용
• 콘솔 로그 모니터링: 브라우저 콘솔 출력 캡처
• 스크린샷 기능: 전체 페이지 또는 특정 요소의 이미지 캡처
• JavaScript 실행: 브라우저 콘솔에서 코드 실행
• 기본 웹 상호 작용: 탐색, 클릭, 양식 작성
• 맞춤형 Puppeteer 실행 옵션: 브라우저 동작 사용자 정의
• 보안 구성: 위험한 실행 옵션에 대한 제어

API

도구

puppeteer_navigate

브라우저에서 URL로 이동합니다.

• 입력:
• url (문자열, 필수): 이동할 URL
• launchOptions (객체, 선택적): PuppeteerJS LaunchOptions. 기본값 null. 변경되고 null이 아니면 브라우저가 재시작됩니다. 예: { headless: true, args: ['--user-data-dir="C:/Data"'] }
• allowDangerous (불리언, 선택적): 보안을 줄이는 위험한 LaunchOptions를 허용합니다. false이면 --no-sandbox, --disable-web-security와 같은 위험한 인수가 오류를 발생시킵니다. 기본값 false.

puppeteer_screenshot

전체 페이지 또는 특정 요소의 스크린샷을 캡처합니다.

• 입력:
• name (문자열, 필수): 스크린샷 이름
• selector (문자열, 선택적): 스크린샷을 찍을 요소의 CSS 선택자
• width (숫자, 선택적, 기본값: 800): 스크린샷 너비
• height (숫자, 선택적, 기본값: 600): 스크린샷 높이
• encoded (불리언, 선택적): true인 경우, 스크린샷을 이진 이미지 콘텐츠 대신 base64로 인코딩된 데이터 URI(텍스트)로 캡처합니다. 기본값 false.

puppeteer_click

페이지의 요소를 클릭합니다.

• 입력:
• selector (문자열): 클릭할 요소의 CSS 선택자

puppeteer_hover

페이지의 요소 위에 마우스를 올립니다.

• 입력:
• selector (문자열): 마우스를 올릴 요소의 CSS 선택자

puppeteer_fill

입력 필드를 채웁니다.

• 입력:
• selector (문자열): 입력 필드의 CSS 선택자
• value (문자열): 채울 값

puppeteer_select

SELECT 태그가 있는 요소를 선택합니다.

• 입력:
• selector (문자열): 선택할 요소의 CSS 선택자
• value (문자열): 선택할 값

puppeteer_evaluate

브라우저 콘솔에서 JavaScript를 실행합니다.

• 입력:
• script (문자열): 실행할 JavaScript 코드

리소스

서버는 두 가지 유형의 리소스에 대한 액세스를 제공합니다:

콘솔 로그 (console://logs)

• 텍스트 형식의 브라우저 콘솔 출력
• 브라우저의 모든 콘솔 메시지 포함

스크린샷 (screenshot://<n>)

• 캡처된 스크린샷의 PNG 이미지
• 캡처 중에 지정된 스크린샷 이름을 통해 액세스 가능

사용 방법

Claude Desktop에서 사용

Puppeteer 서버를 사용하기 위한 Claude Desktop 구성은 다음과 같습니다:

Docker

참고: Docker 구현은 헤드리스 chromium을 사용하는 반면, NPX 버전은 브라우저 창을 엽니다.

{
  "mcpServers": {
    "puppeteer": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "-e", "DOCKER_CONTAINER=true", "mcp/puppeteer"]
    }
  }
}

NPX

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

VS Code에서 사용

VS Code User Settings(JSON) 파일에 다음 JSON 블록을 추가하세요. Ctrl + Shift + P를 누르고 Preferences: Open User Settings (JSON)를 입력하여 이 작업을 수행할 수 있습니다.

선택적으로 작업 공간의 .vscode/mcp.json 파일에 추가할 수 있습니다. 이렇게 하면 다른 사람과 구성을 공유할 수 있습니다.

.vscode/mcp.json 파일에서는 mcp 키가 필요하지 않습니다.

NPX 설치(브라우저 창 열림):

{
  "mcp": {
    "servers": {
      "puppeteer": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
      }
    }
  }
}

Docker 설치(헤드리스 chromium 사용):

{
  "mcp": {
    "servers": {
      "puppeteer": {
        "command": "docker",
        "args": ["run", "-i", "--rm", "--init", "-e", "DOCKER_CONTAINER=true", "mcp/puppeteer"]
      }
    }
  }
}

실행 옵션

Puppeteer의 브라우저 동작을 두 가지 방법으로 사용자 정의할 수 있습니다:

환경 변수

MCP 구성의 env 매개변수에 JSON 인코딩 문자열로 PUPPETEER_LAUNCH_OPTIONS를 설정합니다:

{
  "mcpServers": {
    "mcp-puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"],
      "env": {
        "PUPPETEER_LAUNCH_OPTIONS": "{ \"headless\": false, \"executablePath\": \"C:/Program Files/Google/Chrome/Application/chrome.exe\", \"args\": [] }",
        "ALLOW_DANGEROUS": "true"
      }
    }
  }
}

도구 호출 인수

puppeteer_navigate 도구에 launchOptions 및 allowDangerous 매개변수를 전달합니다:

{
  "url": "https://example.com",
  "launchOptions": {
    "headless": false,
    "defaultViewport": {
      "width": 1280,
      "height": 720
    }
  }
}

빌드

Docker 빌드:

docker build -t mcp/puppeteer -f src/puppeteer/Dockerfile .

라이선스

이 MCP 서버는 MIT 라이선스에 따라 라이선스가 부여됩니다. 이는 MIT 라이선스의 약관 및 조건에 따라 소프트웨어를 자유롭게 사용, 수정 및 배포할 수 있음을 의미합니다. 자세한 내용은 프로젝트 저장소의 LICENSE 파일을 참조하세요.

연결된 구성 요소

• GitHub
• Brave Search
• Fetch